<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../assets/css/combined.css">
	<link rel="shortcut icon" href="./../favicon.ico" />
	<script src="http://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../';
	</script>
	<script src="./../assets/js/combined.js"></script>
	<title>Views - General - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<h1>
					<strong>FuelPHP, a PHP 5.3 Framework</strong>
					Documentation
				</h1>

				<form id="google_search">
					<p>
						<span id="search_clear">&nbsp;</span>
						<input type="submit" name="search_submit" id="search_submit" value="search" />
						<input type="text" value="" id="search_input" name="search_input" />
					</p>
				</form>
			</div>
			<nav>

				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="cse">
			<div id="cse_point"></div>
			<div id="cse_content"></div>
		</div>

		<div id="main">

			<h2>Views</h2>

			<h3 id="what_is_a_view">What is a view?</h3>

			<p>Views are files that present data to the browser. These files enable the separation of logic and presentation for your application. Views are typically html, javascript, or css but can contain variables passed into them from the controller.</p>

			<h3>Creating a view</h3>

			<p>In FuelPHP, Views are located in the <kbd>APPPATH/views</kbd> directory. Views can be located in subdirectories. Views are named by their directory path from the fuel/app/views and the file name, so a view file located <em>fuel/app/views/user/join.php</em> would be named <kbd>user/join</kbd>.</p>

			<p class="note"><strong>Note:</strong> Views are located in <kbd>APPPATH/views</kbd>. Viewmodels are located in <kbd>APPPATH/classes/view</kbd></p>
			<p>Example:</p>

	<pre class="html"><code>&lt;html&gt;
	&lt;head&gt;
		&lt;title>&lt;?php echo $title; ?&gt;&lt;/title>
	&lt;/head&gt;
	&lt;body&gt;
		Welcome, &lt;?php echo $username; ?&gt;.
	&lt;/body&gt;
&lt;/html&gt;
</code></pre>

			<h3 id="using_views">Using views</h3>

			<p>Views in the Fuel framework are very flexible. You can create a single view and nest views within other views. This can be done multiple ways.</p>

			<p><strong>Example View (fuel/app/views/home/index.php):</strong></p>
			<pre class="html"><code>&lt;html&gt;
	&lt;head&gt;
		&lt;title>&lt;?php echo $title; ?&gt;&lt;/title>
	&lt;/head&gt;
	&lt;body&gt;
		Welcome, &lt;?php echo $username; ?&gt;.
	&lt;/body&gt;
&lt;/html&gt;
</code></pre>

			<p><strong>Method 1 (using example view above):</strong></p>

			<pre class="php"><code>class Controller_Home extends Controller
{
	public function action_index()
	{
		$data = array(); //stores variables going to views

		$data['username'] = 'Joe14';
		$data['title'] = 'Home';

		//assign the view to browser output
		return View::forge('home/index', $data);
	}
}</code></pre>

			<p><strong>Method 2 (using example view above):</strong></p>

			<pre class="php"><code>class Controller_Home extends Controller
{
	public function action_index()
	{
		//create the view
		$view = View::forge('home/index');

		//assign variables for the view
		$view->username = 'Joe14';
		$view->title = 'Home';

		//another way to assign variables for the view
		$view->set('username', 'Joe14');
		$view->set('title', 'Home');

		//assign the view to browser output
		return $view;
	}
}</code></pre>

			<h3 id="security">Security</h3>

			<p>Views use output encoding to sanitize anything you pass to them. In a default installation, the security method
				Security::htmlentities() is defined as output filter. You can modify the filters in your applications config.php file.
				If you want to pass something unfiltered, you can use the method <kbd>set($name, $value, false)</kbd>.</p>

			<pre class="php"><code>class Controller_Example extends Controller
{
	public function action_index()
	{
		$view = \View::forge('example');

		// add it filtered, outputs: &amp;lt;strong&amp;gt;not bold because filtered&amp;lt;/strong&amp;gt;
		$view->title = '&lt;strong&gt;not bold because filtered&lt;/strong&gt;';

		// add it unfiltered, outputs: &lt;strong&gt; bold because unfiltered&lt;/strong&gt;
		$view->set('title', '&lt;strong&gt; bold because unfiltered&lt;/strong&gt;', false);

		// or use the set_safe() method, which is identical to set() but defaults to 'false'
		$view->set_safe('title', '&lt;strong&gt; bold because unfiltered&lt;/strong&gt;');

		return $view;
	}
}</code></pre>

			<p>If you don't want your View to work like this, you can pass <kbd>false</kbd> as third argument <kbd>View::forge()</kbd>
			Now anything added to this View object will be unfiltered.  If you then do want some values filtered, you can use
			<kbd>set($name, $value, true)</kbd>.<br />
			You can also globally disable the output filter by setting the application
			configuration value <kbd>security.auto_filter_output</kbd> to <kbd>false</kbd>. For security reasons it is highly recommended
			that you don't do this!</p>

			<p class="note"><strong>Note on objects:</strong> Unless the passed object is of the type View, ViewModel or Closure, it is
			expected to have a <kbd>__toString()</kbd> method and forced to be a string when output filtering is enabled. If you want
			to pass it anyway, you need to use <kbd>set($name, $value, false)</kbd>, but don't forget to filter what you
			use!<br />
			View &amp; ViewModels are expected to contain HTML and take care of their own filtering which is why they're
			not sanitized. Closures cannot be sanitized, and you should take care to ensure this is done within them if
			necessary.</p>

			<h3>Lazy rendering</h3>

			<p>
				When instantiating a view object, only the environment needed to generate output is setup. The view file is not
				being read, no variables will be interpreted, and no output will be rendered.
			</p>
			<p>
				This only happens when you explicitly call the <code>render()</code> method on the view object or when you
				cast the view object to a string (which happens automatically when you echo it). This means no views are processed
				until it's absolutely needed. It also means that Fuel doesn't keep rendered views in memory until it is time to
				send them to the browser.
			</p>

			<h3>Nesting Views</h3>

			<p>Views can also be nested to contain other views. This can be done multiple ways.</p>

			<h3>Example Views</h3>

			<p>fuel/app/views/layout.php</p>

			<pre class="html"><code>&lt;html&gt;
	&lt;head&gt;
		&lt;?php echo $head; ?&gt;
	&lt;/head&gt;
	&lt;body&gt;
		&lt;?php echo $header; ?&gt;
		&lt;?php echo $content; ?&gt;
		&lt;?php echo $footer; ?&gt;
	&lt;/body&gt;
&lt;/html&gt;</code></pre>

			<p>fuel/app/views/head.php</p>

			<pre class="html"><code>&lt;title&gt;&lt;?php echo $title; ?&gt;&lt;/title&gt;</code></pre>

			<p>fuel/app/views/header.php</p>

			<pre class="html"><code>&lt;div class=&quot;logo&quot;&gt;&lt;/div&gt;
&lt;div class=&quot;logo_text&quot;&gt;&lt;?php echo $site_title; ?&gt;&lt;/div&gt;</code></pre>

			<p>fuel/app/views/content.php</p>

			<pre class="html"><code>&lt;h1&gt;&lt;?php echo $title; ?&gt;&lt;/h1&gt;
&lt;div class=&quot;welcome_user&quot;&gt;Welcome &lt;?php echo $username; ?&gt;&lt;/div&gt;</code></pre>

			<p>fuel/app/views/footer.php</p>

			<pre class="html"><code>&lt;div class=&quot;footer&quot;&gt;
	&amp;copy; Copyright &lt;?php echo date('Y');?&gt; &lt;?php echo $site_title; ?&gt;
&lt;/div&gt;</code></pre>

			<h3 id="method_one">Method 1 (using example views above and lazy rendering):</h3>

			<pre class="php"><code>class Controller_Home extends Controller
{
	public function action_index()
	{
		// create the layout view
		$view = View::forge('layout');

		// assign global variables so all views have access to them
		$view->set_global('username', 'Joe14');
		$view->set_global('title', 'Home');
		$view->set_global('site_title', 'My Website');

		//assign views as variables, lazy rendering
		$view->head = View::forge('head');
		$view->header = View::forge('header');
		$view->content = View::forge('content');
		$view->footer = View::forge('footer');

		// return the view object to the Request
		return $view;
	}
}</code></pre>

			<h3 id="method_two">Method 2 (using example views above and forced rendering):</h3>

			<pre class="php"><code>class Controller_Home extends Controller
{
	public function action_index()
	{
		//assign variables
		$data = array();
		$data['title'] = 'Home';
		$data['site_title'] = 'My Website';
		$data['username'] = 'Joe14';

		//assign views as variables, forced rendering
		$views = array();
		$views['head'] = View::forge('head', $data)->render();
		$views['header'] = View::forge('header', $data)->render();
		$views['content'] = View::forge('content', $data)->render();
		$views['footer'] = View::forge('footer', $data)->render();

		// return the rendered HTML to the Request
		return View::forge('layout', $views)->render();
	}
}</code></pre>

			<h3 id="method_two">Method 3 (using example views above, no global data, lazy rendering):</h3>

			<pre class="php"><code>class Controller_Home extends Controller
{
	public function action_index()
	{
		// create the layout view
		$view = View::forge('layout');

		//local view variables, lazy rendering
		$view->head = View::forge('head', array('title' =&gt; 'Home'));
		$view->header = View::forge('header', array('site_title' =&gt; 'My Website'));
		$view->content = View::forge('content', array('username' =&gt; 'Joe14', 'title' =&gt; 'Home'));
		$view->footer = View::forge('footer', array('site_title' =&gt; 'My Website'));

		// return the view object to the Request
		return $view;
	}
}</code></pre>

			<p>See the <a href="../classes/view.html">View Class in the classes section</a> for View's function descriptions.</p>

		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2013 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>
